home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / X11 / XrmGetResource.z / XrmGetResource
Encoding:
C/C++ Source or Header  |  2002-10-03  |  12.1 KB  |  265 lines
  1.  
  2.  
  3.  
  4.      XXXXrrrrmmmmGGGGeeeettttRRRReeeessssoooouuuurrrrcccceeee((((3333XXXX11111111))))XXXX VVVVeeeerrrrssssiiiioooonnnn 11111111 ((((RRRReeeelllleeeeaaaasssseeee 6666....6666))))XXXXrrrrmmmmGGGGeeeettttRRRReeeessssoooouuuurrrrcccceeee((((3333XXXX11111111))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.           XrmGetResource, XrmQGetResource, XrmQGetSearchList,
  10.           XrmQGetSearchResource - retrieve database resources and
  11.           search lists
  12.  
  13.      SSSSYYYYNNNNTTTTAAAAXXXX
  14.           Bool XrmGetResource(_d_a_t_a_b_a_s_e, _s_t_r__n_a_m_e, _s_t_r__c_l_a_s_s,
  15.           _s_t_r__t_y_p_e__r_e_t_u_r_n, _v_a_l_u_e__r_e_t_u_r_n)
  16.                XrmDatabase _d_a_t_a_b_a_s_e;
  17.                char *_s_t_r__n_a_m_e;
  18.                char *_s_t_r__c_l_a_s_s;
  19.                char **_s_t_r__t_y_p_e__r_e_t_u_r_n;
  20.                XrmValue *_v_a_l_u_e__r_e_t_u_r_n;
  21.  
  22.           Bool XrmQGetResource(_d_a_t_a_b_a_s_e, _q_u_a_r_k__n_a_m_e, _q_u_a_r_k__c_l_a_s_s,
  23.           _q_u_a_r_k__t_y_p_e__r_e_t_u_r_n, _v_a_l_u_e__r_e_t_u_r_n)
  24.                XrmDatabase _d_a_t_a_b_a_s_e;
  25.                XrmNameList _q_u_a_r_k__n_a_m_e;
  26.                XrmClassList _q_u_a_r_k__c_l_a_s_s;
  27.                XrmRepresentation *_q_u_a_r_k__t_y_p_e__r_e_t_u_r_n;
  28.                XrmValue *_v_a_l_u_e__r_e_t_u_r_n;
  29.  
  30.           typedef XrmHashTable *XrmSearchList;
  31.  
  32.           Bool XrmQGetSearchList(_d_a_t_a_b_a_s_e, _n_a_m_e_s, _c_l_a_s_s_e_s,
  33.           _l_i_s_t__r_e_t_u_r_n, _l_i_s_t__l_e_n_g_t_h)
  34.                XrmDatabase _d_a_t_a_b_a_s_e;
  35.                XrmNameList _n_a_m_e_s;
  36.                XrmClassList _c_l_a_s_s_e_s;
  37.                XrmSearchList _l_i_s_t__r_e_t_u_r_n;
  38.                int _l_i_s_t__l_e_n_g_t_h;
  39.  
  40.           Bool XrmQGetSearchResource(_l_i_s_t, _n_a_m_e, _c_l_a_s_s, _t_y_p_e__r_e_t_u_r_n,
  41.           _v_a_l_u_e__r_e_t_u_r_n)
  42.                XrmSearchList _l_i_s_t;
  43.                XrmName _n_a_m_e;
  44.                XrmClass _c_l_a_s_s;
  45.                XrmRepresentation *_t_y_p_e__r_e_t_u_r_n;
  46.                XrmValue *_v_a_l_u_e__r_e_t_u_r_n;
  47.  
  48.      AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  49.           _c_l_a_s_s     Specifies the resource class.
  50.  
  51.           _c_l_a_s_s_e_s   Specifies a list of resource classes.
  52.  
  53.           _d_a_t_a_b_a_s_e  Specifies the database that is to be used.
  54.  
  55.           _l_i_s_t      Specifies the search list returned by
  56.                     _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t.
  57.  
  58.           _l_i_s_t__l_e_n_g_t_h
  59.                     Specifies the number of entries (not the byte
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 10/3/02)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      XXXXrrrrmmmmGGGGeeeettttRRRReeeessssoooouuuurrrrcccceeee((((3333XXXX11111111))))XXXX VVVVeeeerrrrssssiiiioooonnnn 11111111 ((((RRRReeeelllleeeeaaaasssseeee 6666....6666))))XXXXrrrrmmmmGGGGeeeettttRRRReeeessssoooouuuurrrrcccceeee((((3333XXXX11111111))))
  71.  
  72.  
  73.  
  74.                     size) allocated for list_return.
  75.  
  76.           _l_i_s_t__r_e_t_u_r_n
  77.                     Returns a search list for further use.
  78.  
  79.           _n_a_m_e      Specifies the resource name.
  80.  
  81.           _n_a_m_e_s     Specifies a list of resource names.
  82.  
  83.           _q_u_a_r_k__c_l_a_s_s
  84.                     Specifies the fully qualified class of the value
  85.                     being retrieved (as a quark).
  86.  
  87.           _q_u_a_r_k__n_a_m_e
  88.                     Specifies the fully qualified name of the value
  89.                     being retrieved (as a quark).
  90.  
  91.           _q_u_a_r_k__t_y_p_e__r_e_t_u_r_n
  92.                     Returns the representation type of the destination
  93.                     (as a quark).
  94.  
  95.           _s_t_r__c_l_a_s_s Specifies the fully qualified class of the value
  96.                     being retrieved (as a string).
  97.  
  98.           _s_t_r__n_a_m_e  Specifies the fully qualified name of the value
  99.                     being retrieved (as a string).
  100.  
  101.           _s_t_r__t_y_p_e__r_e_t_u_r_n
  102.                     Returns the representation type of the destination
  103.                     (as a string).
  104.  
  105.           _t_y_p_e__r_e_t_u_r_n
  106.                     Returns data representation type.
  107.  
  108.           _v_a_l_u_e__r_e_t_u_r_n
  109.                     Returns the value in the database.
  110.  
  111.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  112.           The _X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e functions retrieve a
  113.           resource from the specified database.  Both take a fully
  114.           qualified name/class pair, a destination resource
  115.           representation, and the address of a value (size/address
  116.           pair). The value and returned type point into database
  117.           memory; therefore, you must not modify the data.
  118.  
  119.           The database only frees or overwrites entries on
  120.           _X_r_m_P_u_t_R_e_s_o_u_r_c_e, _X_r_m_Q_P_u_t_R_e_s_o_u_r_c_e, or _X_r_m_M_e_r_g_e_D_a_t_a_b_a_s_e_s.  A
  121.           client that is not storing new values into the database or
  122.           is not merging the database should be safe using the address
  123.           passed back at any time until it exits.  If a resource was
  124.           found, both _X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e return _T_r_u_e;
  125.           otherwise, they return _F_a_l_s_e.
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 10/3/02)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      XXXXrrrrmmmmGGGGeeeettttRRRReeeessssoooouuuurrrrcccceeee((((3333XXXX11111111))))XXXX VVVVeeeerrrrssssiiiioooonnnn 11111111 ((((RRRReeeelllleeeeaaaasssseeee 6666....6666))))XXXXrrrrmmmmGGGGeeeettttRRRReeeessssoooouuuurrrrcccceeee((((3333XXXX11111111))))
  137.  
  138.  
  139.  
  140.           The _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t function takes a list of names and
  141.           classes and returns a list of database levels where a match
  142.           might occur.  The returned list is in best-to-worst order
  143.           and uses the same algorithm as _X_r_m_G_e_t_R_e_s_o_u_r_c_e for
  144.           determining precedence.  If list_return was large enough for
  145.           the search list, _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t returns _T_r_u_e; otherwise,
  146.           it returns _F_a_l_s_e.
  147.  
  148.           The size of the search list that the caller must allocate is
  149.           dependent upon the number of levels and wildcards in the
  150.           resource specifiers that are stored in the database.  The
  151.           worst case length is %3 sup n%, where _n is the number of
  152.           name or class components in names or classes.
  153.  
  154.           When using _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t followed by multiple probes for
  155.           resources with a common name and class prefix, only the
  156.           common prefix should be specified in the name and class list
  157.           to _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t.
  158.  
  159.           The _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e function searches the specified
  160.           database levels for the resource that is fully identified by
  161.           the specified name and class.  The search stops with the
  162.           first match.  _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e returns _T_r_u_e if the
  163.           resource was found; otherwise, it returns _F_a_l_s_e.
  164.  
  165.           A call to _X_r_m_Q_G_e_t_S_e_a_r_c_h_L_i_s_t with a name and class list
  166.           containing all but the last component of a resource name
  167.           followed by a call to _X_r_m_Q_G_e_t_S_e_a_r_c_h_R_e_s_o_u_r_c_e with the last
  168.           component name and class returns the same database entry as
  169.           _X_r_m_G_e_t_R_e_s_o_u_r_c_e and _X_r_m_Q_G_e_t_R_e_s_o_u_r_c_e with the fully qualified
  170.           name and class.
  171.  
  172.      MMMMAAAATTTTCCCCHHHHIIIINNNNGGGG RRRRUUUULLLLEEEESSSS
  173.           The algorithm for determining which resource database entry
  174.           matches a given query is the heart of the resource manager.
  175.           All queries must fully specify the name and class of the
  176.           desired resource (use of the characters ``*'' and ``?'' are
  177.           not permitted).  The library supports up to 100 components
  178.           in a full name or class.  Resources are stored in the
  179.           database with only partially specified names and classes,
  180.           using pattern matching constructs.  An asterisk (*) is a
  181.           loose binding and is used to represent any number of
  182.           intervening components, including none.  A period (.) is a
  183.           tight binding and is used to separate immediately adjacent
  184.           components.  A question mark (?) is used to match any single
  185.           component name or class.  A database entry cannot end in a
  186.           loose binding; the final component (which cannot be the
  187.           character ``?'') must be specified.  The lookup algorithm
  188.           searches the database for the entry that most closely
  189.           matches (is most specific for) the full name and class being
  190.           queried.  When more than one database entry matches the full
  191.           name and class, precedence rules are used to select just
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 10/3/02)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      XXXXrrrrmmmmGGGGeeeettttRRRReeeessssoooouuuurrrrcccceeee((((3333XXXX11111111))))XXXX VVVVeeeerrrrssssiiiioooonnnn 11111111 ((((RRRReeeelllleeeeaaaasssseeee 6666....6666))))XXXXrrrrmmmmGGGGeeeettttRRRReeeessssoooouuuurrrrcccceeee((((3333XXXX11111111))))
  203.  
  204.  
  205.  
  206.           one.
  207.  
  208.           The full name and class are scanned from left to right (from
  209.           highest level in the hierarchy to lowest), one component at
  210.           a time.  At each level, the corresponding component and/or
  211.           binding of each matching entry is determined, and these
  212.           matching components and bindings are compared according to
  213.           precedence rules.  Each of the rules is applied at each
  214.           level before moving to the next level, until a rule selects
  215.           a single entry over all others.  The rules, in order of
  216.           precedence, are:
  217.  
  218.           1.   An entry that contains a matching component (whether
  219.                name, class, or the character ``?'')  takes precedence
  220.                over entries that elide the level (that is, entries
  221.                that match the level in a loose binding).
  222.  
  223.           2.   An entry with a matching name takes precedence over
  224.                both entries with a matching class and entries that
  225.                match using the character ``?''.  An entry with a
  226.                matching class takes precedence over entries that match
  227.                using the character ``?''.
  228.  
  229.           3.   An entry preceded by a tight binding takes precedence
  230.                over entries preceded by a loose binding.
  231.  
  232.      SSSSEEEEEEEE AAAALLLLSSSSOOOO
  233.           XrmInitialize(3X11), XrmMergeDatabases(3X11),
  234.           XrmPutResource(3X11), XrmUniqueQuark(3X11)
  235.           _X_l_i_b - _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                                          (printed 10/3/02)
  262.  
  263.  
  264.  
  265.